home *** CD-ROM | disk | FTP | other *** search
/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / WIN_PRO / DS-1.ZIP;1 / IPD183.DOC < prev    next >
Encoding:
Text File  |  1992-02-15  |  13.9 KB  |  463 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.             Compiling Version 8.5 of Icon for MS-DOS
  8.  
  9.                         Ralph E. Griswold
  10.     Department of Computer Science, The University of Arizona
  11.  
  12.  
  13.  
  14.    The implementation of the Icon programming language is large
  15. and complex [1-4].  It is, however, written almost entirely in C
  16. and RTL [4], a superset of C for which a translator to C is pro-
  17. vided. Icon is designed to be portable to a wide range of comput-
  18. ers and operating systems.  This document concerns the compila-
  19. tion of Version 8.5 of Icon for MS-DOS.
  20.  
  21.  
  22. 1.__Requirements
  23.  
  24.    Version 8.5 of Icon runs on computers with 8086/88/x86-family
  25. processors. IBM hardware compatibility is not required. Either
  26. MS-DOS or PC-DOS, Version 3.0 or higher, is needed.  Specific C
  27. compilers may impose more stringent requirements.
  28.  
  29.    Icon requires a robust and full-featured C compiler.  A 16-bit
  30. compiler must support the large memory model.  ANSI compatibility
  31. is important but not essential.  As of the date of this document,
  32. Version 8.5 of Icon for MS-DOS has been successfully compiled
  33. with the following C compilers:
  34.  
  35.         Borland C++ 2.0
  36.         Intel Code Builder 1.0
  37.         Metaware High C 2.3
  38.         Microsoft C 6.00 (MS-DOS and OS/2)
  39.         Turbo C 2.0
  40.         Zortech C++ 3.0
  41.  
  42. The Version 8.5 source code contains the necessary conditional
  43. code for these compilers.
  44.  
  45.    The use of another C compiler will involve some work, since
  46. there is code that is conditional on the characteristics of
  47. specific C compilers.
  48.  
  49.    Icon's co-expressions require an assembly-language context
  50. switch.  An appropriate assembler therefore is necessary to pro-
  51. vide this feature when building Icon entirely from the source
  52. code. However, object files for context switches are provided,
  53. where available, for persons who do not have an assembler.
  54.  
  55.    The source code for Icon and test programs occupies about 2MB
  56. of disk space. A total of about 3.5MB is needed to completely
  57. build and test Icon, although it is possible to get by with less
  58. by building incrementally.
  59.  
  60.  
  61.  
  62.  
  63.  
  64. IPD183                        - 1 -              February 9, 1992
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73. 2.__Organization_of_the_Implementation
  74.  
  75.    The source code for Icon is organized in a hierarchy.  Files
  76. for various components of Icon are packaged in LHarc (lzh) for-
  77. mat.  A copy of lharc.exe is included in the distribution.
  78. Instructions for unloading the files are provided on the distri-
  79. bution diskettes.
  80.  
  81.    If the Icon hierarchy is rooted in \icon, the directories
  82. after unloading are:
  83.           |-bin------                        executable binaries
  84.           |
  85.           |                     |-borland--  Borland C++
  86.           |                     |-codebldr-  Intel Code Builder
  87.           |                     |-highc----  Metaware High C
  88.           |-config---|-msdos----|-microsft-  Microsoft C
  89.           |          |          |-turbo----  Turbo C
  90.           |          |          |-zortech--  Zortech C++
  91.           |          |
  92.           |          |-os2------|-microsft-  Microsoft C
  93.           |
  94.           |          |-common---             common source
  95.           |          |-h--------             headers
  96. |-icon----|-src------|-icont----             Icon translator source
  97.           |          |-preproc--             pre-processor source
  98.           |          |-rtt------             run-time translator source
  99.           |          |-runtime--             Icon run-time source
  100.           |
  101.           |-tests----|-general--|-local----  local test results
  102.                                 |-stand----  standard test results
  103.  
  104.  
  105.    The distribution diskettes also contain documentation and some
  106. tools that may be useful in building and testing Icon. See README
  107. on the distribution diskettes.
  108.  
  109. Source_Files
  110.  
  111.    The six source-code sub-directories under src contain the fol-
  112. lowing components of Icon:
  113.  
  114.      common    files common to different components of Icon.
  115.  
  116.      h         header files used by files in the other direc-
  117.                tories.
  118.  
  119.      icont     source code for icont, the translator and linker
  120.                that converts an Icon source-language program into
  121.                an icode file.
  122.  
  123.      preproc   source code for an ANSI C pre-processor used by
  124.                the run-time translator.
  125.  
  126.  
  127.  
  128.  
  129.  
  130. IPD183                        - 2 -              February 9, 1992
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.      rtt       source code for rtt, a program used in building
  140.                iconx.
  141.  
  142.      runtime   source code for iconx, the executor and run-time
  143.                system for icode files.
  144.  
  145. Configuration_Directories
  146.  
  147.    In order to simplify the process of compiling Icon under dif-
  148. ferent C compilers, files that are compiler-specific, including
  149. batch and linker files, are provided in subdirectories of the
  150. config directory.  The MS-DOS configurations presently are:
  151.  
  152.         borland   Borland C++
  153.         codebldr  Intel Code Builder
  154.         highc     Metaware High C
  155.         microsft  Microsoft C for MS-DOS
  156.         turbo     Turbo C
  157.         zortech   Zortech C++
  158.  
  159. The use of these configuration directories is described in next
  160. section. Note: Some files contain path information that may need
  161. to be changed for a particular configuration.
  162.  
  163.  
  164. 3.__Compiling_Icon_for_an_Existing_Configuration
  165.  
  166.    Before starting to compile Icon, be sure your C compiler is
  167. properly installed and that any paths that it needs are properly
  168. set.
  169.  
  170. Setting_up_Files
  171.  
  172.    The first step in the compilation process is to set up the
  173. files needed for compilation and linking.  If you are using one
  174. of the C compilers mentioned above, there is a .bat file in the
  175. top level of the Icon hierarchy (e.g. \icon) whose name
  176. corresponds to the C compiler.  Executing the .bat file performs
  177. the configuration.  For example, if you want to configure Version
  178. 8.5 of Icon to compile under Microsoft C, just type
  179.  
  180.         microsft
  181.  
  182. These batch files first erase files that may be left over from a
  183. previous configuration ("File not found" is normal at this
  184. point), and then they copy in compiler-specific scripts and
  185. source files.
  186.  
  187.    A file containing compiler-specific information, status, is
  188. also copied into the top level of the Icon hierarchy.  Read this
  189. file before proceeding, since it may contain information needed
  190. to build Icon.
  191.  
  192.  
  193.  
  194.  
  195.  
  196. IPD183                        - 3 -              February 9, 1992
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205. Optional_Features
  206.  
  207.    MS-DOS Functions: There are a few functions specially designed
  208. for using Icon under MS-DOS that are not part of Icon's standard
  209. function repertoire.  The functions are described in [5].  These
  210. functions normally are included in the compilation process. If
  211. you wish to eliminate them (which decreases the size of iconx by
  212. a few thousand bytes), remove
  213.  
  214.         #define DosFncs
  215.  
  216. from src\h\define.h.
  217.  
  218.    Large Integers: Icon has facilities for large-integer arith-
  219. metic, but these facilities are disabled by default in MS-DOS
  220. Icon because they increase the size of iconx substantially (20-
  221. 30KB). If you have enough RAM and wish to enable large-integer
  222. arithmetic, remove the following line from src\h\define.h:
  223.  
  224.         #define NoLargeInts
  225.  
  226.  
  227. Compilation
  228.  
  229.    A public-domain version of a UNIX-style make utility is pro-
  230. vided on the distribution diskettes. Makefiles for each subdirec-
  231. tory are copied into place during configuration. This make util-
  232. ity is different from (and more powerful) than the make utilities
  233. provided by present MS-DOS C compilers. If you do not want to use
  234. it, there is a build.bat file in each source subdirectory that
  235. compiles and links all files without using make.
  236.  
  237.    The steps in building Icon follow. Read the notes at the end
  238. of this section before proceeding.
  239.  
  240.      1. Go to src\common and do either make or build.  This pro-
  241.      duces object files needed elsewhere.
  242.  
  243.      2. Go to src\icont and do either make or build.  This pro-
  244.      duces icont.exe and copies it to bin.
  245.  
  246.      3. Go to src\runtime and do either make or build.  This pro-
  247.      duces iconx.exe and copies it to bin.
  248.  
  249. Notes:
  250.  
  251.      1. In runtime, RTL files (with the extension .r) are
  252.      translated by rtt to C files (with the extension .c), which
  253.      are then compiled.  An x is prepended to the name of the C
  254.      file. For example, translation of cnv.r produces xcnv.c.
  255.  
  256.      2. The steps above do not include building rtt.exe. This is
  257.      because a working rtt.exe cannot be built under some C com-
  258.      pilers.  Instead, an rtt.exe is included with the source
  259.  
  260.  
  261.  
  262. IPD183                        - 4 -              February 9, 1992
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.      distribution and copied to bin as the result of setting up
  272.      Icon files. If you nonetheless wish to build rtt.exe, go to
  273.      src\rtt and do either make or build. Preserve the distri-
  274.      buted copy of tt.exe first, in case you run into trouble.
  275.  
  276.      3. The build in src\runtime may fail if there is not enough
  277.      available RAM when using make. This is most likely when pro-
  278.      cessing the RTL file interp.r. If this happens, first try
  279.      build. If that doesn't work, do the necessary steps manually
  280.      from the command line. For interp.r first do
  281.  
  282.              ..\..\bin\rtt -x interp.r
  283.  
  284.      and then compile the resulting xinterp.c file (note the pre-
  285.      fixed x) using the C compiler options specified in the
  286.      Makefile or batch script.
  287.  
  288.      4. On some platforms, a linking step may indicate an error
  289.      but nonetheless produce a good .exe file. See the
  290.      corresponding status file.
  291.  
  292.    As noted above, The executable files needed to run Icon are
  293. automatically copied to the bin directory.  You may wish to move
  294. them to a place on your PATH.
  295.  
  296.  
  297. 4.__Configuring_Icon_for_a_New_C_Compiler
  298.  
  299.    If you want to build Icon under a C compiler for which there
  300. presently is no configuration, set up a configuration directory
  301. for it and copy files from a configuration that is similar to
  302. your C compiler. See [6] for information on modifying the new
  303. configuration to suit your C compiler.
  304.  
  305.    If you are successful in building Icon with the new compiler,
  306. please send the modified files to the Icon Project as described
  307. in Section 7 so that they can be incorporated in future releases.
  308.  
  309.  
  310. 5.__Testing
  311.  
  312.    A suite of test programs is provided in tests\general. The
  313. expected output of the test programs is in tests\general\stand;
  314. tests\general\local is provided for local output.
  315.  
  316.    The directory tests contains several files of the form
  317. name.lst, which consist of the names of test programs. Testing
  318. can be done with these files and the program runtests provided
  319. with the distribution.  The form is:
  320.  
  321.         runtests name.lst > name.res
  322.  
  323. where name is one of the files mentioned above. As a result,
  324. name.res contains a list showing differences.
  325.  
  326.  
  327.  
  328. IPD183                        - 5 -              February 9, 1992
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.    Note: Local output may differ in some cases from the output in
  338. stand.  This may be due to compiler or configuration differences.
  339. In particular, test output from 16- and 32-bit C compilers may
  340. differ because of different constants used in dynamic hashing. In
  341. the case of differences, look at the corresponding .icn file for
  342. a possible explanation.
  343.  
  344.  
  345. 6.__The_Implementation_Book
  346.  
  347.    If you are interested in the larger view of the implementation
  348. of Icon, or if you are interested in modifying or extending Icon,
  349. you may want to acquire the book on the implementation [1].  This
  350. book concentrates on the run-time system and covers data struc-
  351. tures, the virtual machine, the interpreter, the implementation
  352. of generators, and storage management.
  353.  
  354.    The implementation book corresponds to Version 6 of the Icon
  355. source code.  There have been several changes in the source code
  356. between Version 6 and the present version. Supplementary documen-
  357. tation describing these changes is available free of charge from
  358. the Icon Project [2-4].
  359.  
  360.  
  361. 7.__Trouble_Reports_and_Feedback
  362.  
  363.    If you run into problems, contact the Icon Project:
  364.  
  365.         Icon Project
  366.         Department of Computer Science
  367.         Gould-Simpson Building
  368.         The University of Arizona
  369.         Tucson, AZ   85721
  370.         U.S.A.
  371.         (602) 621-8448 (voice)
  372.         (602) 621-4246 (fax)
  373.         icon-project@cs.arizona.edu     (Internet)
  374.         ... {uunet, allegra, noao}!arizona!icon-project     (uucp)
  375.  
  376.  
  377.    We cannot guarantee to solve your problems, but we will try.
  378. We also may be able to place you in contact with other persons
  379. who are compiling Icon and who may have similar problems.
  380.  
  381.    Please also let us know of any suggestions for improvements to
  382. the compilation process and its documentation.
  383.  
  384. Acknowledgements
  385.  
  386.    Many persons have been involved in the implementation of Icon.
  387. Cheyenne Wills did most of the original work to adapt Icon for
  388. use under MS-DOS.  Clint Jeffery, Gregg Townsend, and Ken Walker
  389. collaborated with the author on Version 8.5.
  390.  
  391.  
  392.  
  393.  
  394. IPD183                        - 6 -              February 9, 1992
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403. References
  404.  
  405.  
  406. 1.   R. E. Griswold and M. T. Griswold, The Implementation of the
  407.      Icon Programming Language, Princeton University Press, 1986.
  408.  
  409. 2.   R. E. Griswold, Supplementary Information for the
  410.      Implementation of Version 8 of Icon, The Univ. of Arizona
  411.      Icon Project Document IPD112, 1990.
  412.  
  413. 3.   R. E. Griswold, Supplementary Information for the
  414.      Implementation  of Version 8.5 of Icon, The Univ. of Arizona
  415.      Icon Project Document IPD180, 1992.
  416.  
  417. 4.   K. Walker, An Implementation Language for Icon Run-Time
  418.      Routines, The Univ. of Arizona Icon Project Document IPD79,
  419.      1989.
  420.  
  421. 5.   R. E. Griswold, Version 8.5 of Icon for MS-DOS, The Univ. of
  422.      Arizona Icon Project Document IPD181, 1992.
  423.  
  424. 6.   R. E. Griswold, C. L. Jeffery, G. M. Townsend and K. Walker,
  425.      Configuring the Source Code for Version 8.5 of Icon, The
  426.      Univ. of Arizona Icon Project Document IPD182, 1992.
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460. IPD183                        - 7 -              February 9, 1992
  461.  
  462.  
  463.